Before reading this section take a moment and run tutorial 3, knowing what the GUI does will help in understanding the code behind it.
This tutorial has two versions, Arexx and 'C'. The 'C' tutorial is after the Arexx one.
TUTORIAL 3 AREXX
---------------
This tutorial deals with modifying a GUI after it has been opened. You should make sure you understand tutorial 2 before reading further.
Three new gadgets have added to the gui. The load and save gadgets on the lower left, and a get file gadget that you do not see. The getfile gadget is unattached (ua) so it is not displayed in the gui. More on the getfile gadget later.
The window definition line (in buildGUI:) has the modify option added to it. This means the pipe will look for modify commands after you fist open the window, and after each event is sent. Any number of modify commands can be written to the pipe, including 0 (none). After writing the modify commands 'continue' must be sent to the pipe to tell it to start sending events. After you get an event the pipe starts waiting for modify commands again.
Only two changes are made in the program flow.
1. After BUILDGUI is called to build and open the window we send a modify command to the pipe.
topipe('id 'savegad' dis 1 ref')
The id specifies the save gadget, 'dis 1' disables it, and 'ref' refreshes it so the changes will show. (we want the save gadget disabled because the name gadget is empty at start up, and we need a name before we can save).
2. In the mail loop a 'continue' is written to the pipe BEFORE we wait for an event. This tells to pipe to stop looking for modify commands and send an event.
After an event is read from the pipe it automatically starts looking for more modify events. This means that modify commands can be used immediately after receiving an event from the pipe.
RESETFORM
In tutorial 2 we had to close then open the GUI to reset its contents. With modify commands we can do this with the gui remaining open. The function resetform is near the end of tutorial3.rx.
This function sends a modify command for each of the gadgets resetting them to the default values. It also disables the save gadget.
SAVEFORM
This function is called when the user hits the save gadget. It writes the forms contents to a file in 't:'. The files name is the text from the name gadget with '.formdemo' appended to it. The save gadget is disabled unless the name gadget contains text. See the handling of namegad in the GADGET: routine.
LOADFORM
This function makes use of the unattached GETFILE gadget. A modify command is used to set the file name in the file requester, and to open the requester itself. The pattern used in the file requester was set when the gadget was created in the BUILDGUI routine.
call writeln(ca,'id 'getfilegad' fn "t:" s 1')
'fn "t:"' sets the file requester to the drawer T:. 's 1' opens the requester.
The return from the pipe to this modify command is read and parsed to get the file selected and to test if the user selected a file or aborted the requester. The reply from the pipe is ...
SUCCESS ["filename"]
Success is 0 if the user aborts the file requester, non zero if a file is selected. The file name is always returned in quotes since multiple files can be selected in some situations. (but not this situation).
If the user selected a file, it is opened and the contents placed in the GUI. No error checking is done on the file in order to keep the tutorial clear and easy to understand.
TUTORIAL 3 in C
---------------
This tutorial deals with modifying a GUI after it has been opened. You should make sure you understand tutorial 2 before reading further.
int buildgui(struct GUIpipe * GP);
The window definition line (in buildgui()) has the modify option added to it. This means the pipe will look for modify commands after you fist open the window, and after each event is sent. Any number of modify commands can be written to the pipe, including 0 (none). After writing the modify commands 'continue' must be sent to the pipe to tell it to send an event. After you get an event the pipe starts waiting for modify commands again.
Three new gadgets have added to the gui. The load and save gadgets on the lower left, and a get file gadget that you do not see. The getfile gadget is unattached (ua) so it is not displayed in the gui. More on the getfile gadget later.
int main( int argc, char *argv[]);
Only two changes are made in the program flow.
1. After buildgui() is called to build and open the window we send a modify command to the pipe.
topipe(GP,"id %ld dis 1 ref\n",savegad);
The id specifies the save gadget, 'dis 1' disables it, and 'ref' refreshes it so the changes will show. (we want the save gadget disabled because the name gadget is empty at start up, and we need a name before we can save).
2. In the main loop a 'continue' is written to the pipe BEFORE we wait for an event. This tells to pipe to stop looking for modify commands and send an event.
After an event is read from the pipe it automatically starts looking for more modify events. This means that modify commands can be used immediately after receiving an event from the pipe.
int gadgets(struct GUIpipe * GP);
The 'loadgad' and 'savegad' gadgets are recognised, and the handling of 'namegad' and 'resetgad' have changed.
In tutorial 2 we had to close then open the GUI to reset its contents. With modify commands we can do this with the gui remaining open. We set our default form information and call updategui().
Namegad enables or disables the savegad. If no name is set we can not generate a filename to save the information to.
int updategui(struct GUIpipe * GP);
This routine updates the GUI to show the values we have stored internaly. A modify line is sent for each gadget. The function updateform is near the end of tutorial3.rx.
int saveform(VOID);
This function is called when the user hits the save gadget. It writes the forms contents to a file in 't:'. The files name is the text from the name gadget with '.formdemo' appended to it. The save gadget is disabled unless the name gadget contains text. See the handling of namegad in the gadget() routine.
int loadform(struct GUIpipe * GP);
This function makes use of the unattached GETFILE gadget. A modify command is used to set the file name in the file requester, and to open the requester itself. The pattern used in the file requester was set when the gadget was created in the BUILDGUI routine.
FPrintf(GP->file,"id %ld fn \"t:\" s 1\n",getfilegad);
if (getevent(GP)) return(1);
'fn "t:"' sets the file requester to the drawer T:. 's 1' opens the requester.
The return from the pipe to this modify command is read and parsed as an event since it does not return the usual 'ok'. The reply from the pipe is ...
SUCCESS ["filename"]
Success is 0 if the user aborts the file requester, non zero if a file is selected. The file name is always returned in quotes since multiple files can be selected in some situations. (but not this situation).
If the user selected a file, it is opened and the contents parsed into out internal form information. Then updategui() is called.. No error checking is done on the file in order to keep the tutorial clear and easy to follow.
__stdargs int topipe(struct GUIpipe * GP, UBYTE * data,...);
int getline(struct GUIpipe * GP);
int gperror(struct GUIpipe * GP,int error);
int getevent(struct GUIpipe * GP);
int menu(struct GUIpipe * GP);
UBYTE * eventstr(struct GUIpipe * GP, int num);
VOID setdefaults(VOID);
These routines have not been changed from Tutorial 2.
